
                         !SoundCon
                         =========

By Rick Hudson (rhudson@paradise.net.nz)

This software is released under the GNU Public Licence (GPL). See the file
'COPYING' which should have accompanies this application for specific licence
details.

Note that versions of SoundCon which were released as FreeWare (including
some v1.61 archives) should still have their Freeware licences honoured.
Only archives explicitly stated as GPL versions can be redistributed in
modified form acording to the conditions of the GPL.


Contents
========

  1     Summary
  2     Other documentation
  3     Supported formats
  4     Using SoundCon
  4.1     Loading a sample
  4.2     Changing the interpretation
  4.3     Listening to the sample
  4.3.1     Controlling playback
  4.3.2     Volume
  4.3.3     Mono-echo mode
  4.3.4     Section mode
  4.3.5     Looping mode
  4.4     Converting the sample to another format
  4.4.1     Options
  4.5     Preferences
  4.5.1     Default conversion format
  4.5.2     Default raw interpretation
  4.5.3     Auto actions on load
  4.5.4     File naming
  4.5.5     Sound configuration
  4.5.6     General options
  4.6     Queue processing
  4.6.1     Loading the queue
  4.6.2     Loading a queued sample
  4.6.3     Batch conversion
  4.6.4     The queue menu
  4.7     Using SoundCon with ArcWeb
  5     History/Future
  6     Problems?
  7     Acknowledgements



1. Summary
==========

SoundCon is an application for basic sound sample format conversion on the
Archimedes. It can read and write samples in a variety of formats common on
various computer platforms and can directly playback most the formats it can
read (without converting it first). An important feature of SoundCon is that
all processing and playback is done from disc meaning that the only memory
required is for the application itself and there is no limit to the sample
size.

As of version 1.40 SoundCon can respond to render requests from ArcWeb so
that WWW sounds can be played by just clicking on them.

See the version history in the !SoundCon.Docs.HistFuture file for a summary
of changes and additions to this version.


2. Other documentation
======================

The Docs directory within !SoundCon contains further information on the
PlaySample module, the various sound formats supported, version history and
possible/probable future developments. The Formats file contains format
descriptions, what sub-formats are and aren't supported, limitations of them
and which ones can be played without conversion.

Interactive help is supported. Theoretically, you should be able to stop
reading this now and use that.


3. Supported formats
====================

   Major formats       sub-formats

   Audio IFF           8/16 bit, mono/stereo
   Armadeus            n/a (8 bit mono signed linear)
   ARMovie             8/16 bit, (un)signed linear, VIDC, mono/stereo
   Sun Audio           8 bit A/-law, 8 bit lin, 16 bit lin, mono/stereo
   AudioWorks          8/16 bit (un)signed, A/-law, VIDC, mono/stereo
   Datavox             8/16 bit (un)signed, -law, VIDC, mono/stereo
   IFF/8SVX            n/a (8 bit mono signed linear)
   Psion S3a           n/a (8 bit mono A-law 8kHz)
   VOC                 n/a (8 bit mono unsigned linear)
   Voice modules       4 volume modes, fixed/var frequency, voice/transient
   RIFF WAVE           8/16 bit PCM, A/-law, MS/DVI ADPCM, mono/stereo
   Raw data            8/16 bit, (un)signed lin, A/-law, VIDC, mono/stereo

For more information on these formats see the file Docs.Formats which
describes in more details what the formats can support and what the menu
sub-options do.


                              =================
                              4. Using SoundCon
                              =================

4.1  Loading a sample
=====================

SoundCon is sample converter so it can't do anything until you give a
sample. Drag a file onto the icon bar icon or any of it's windows to 'open'
the sample. The settings of the preferences may cause some actions to happen
automatically at this point (see later) but the default is not do anything
except open the sample information window (click select on the icon bar icon
to open it if you need to). This window displays information about the file
loaded. If the format is not recognised (or a recognisable format is
unsupported - WAVEs have several such formats) then an error message is
reported and sample is loaded as raw data.


4.2  Changing the interpretation
================================

Recognised formats will not usually have to be fiddled with but raw data
will probably have to have the interpretation of the data changed to make
it sound right - this is largely a trial and error process.

At the bottom of the sample info window (click on Toggle Size or scroll
down) there is the interpretation format and frequency - use the pop-up
menus to change these. The format selections are summarised by interactive
help (if your version of RISC OS isn't too old) and described in more detail
in the file Docs.Formats.

The interpretation frequency sets how many sample frames per second to
assume. A sample frame is the samples on all channels at any given point and
so frames per second means samples per channel per second. The menu provides
a list of common frequencies as well as a writable entry for other
frequencies.


4.3  Listening to the sample
============================

The playback control window can be opened by clicking Adjust on the icon bar
icon or by selecting the menu item in the sample info window or icon bar
menus. The sample will be played based on the format and frequency set in the
Interpret As section of the sample info window. An exception to this are
samples that cannot be interpreted as raw data by SoundCon (ADPCM and
Audioworks formats) which can only be played in their original format.

Note that the ADPCM play routines are quite CPU intensive (since they
decompress on the fly) and the sound quality will probably suffer when
interrupts are used heavily (eg lots of disc activity).


4.3.1  Controlling playback

The CD-style buttons control the playback and their use should is as follows:

  o    Stop. Stop a sample playing and reset the position to the start.
  >    Play. Start playing a sample. Also unpauses if paused.
  ||   Pause. Stop playing but retain the current position. Click again to
       resume playback.
  <<   Rewind. Move the position back by 1/100th of the sample length and
       return to play or pause as appropriate. If sample is stopped then
       pause mode is entered. Holding the button down 
  >>   Cue. As rewind but move forward 1/100th of the sample length.
  |<<  Previous sample. If the play position is near or at the beginning and
       the queue pointer is not on the first entry then the previous sample
       is loaded. If the play position is *not* near the beginning then it
       rewinds to the start.
  >>|  If the queue pointer is not at the end of the queue then the next
       queued item is loaded.

The slider marking the sample progress can be dragged around as an
alternative to setting the sample position with the cue and rewind buttons.
Play or pause is resumed as appropriate. If the sample has not been started
then pause mode is entered.

4.3.2  Volume

The volume slider on the right controls the volume and the speaker button
(top button) toggles the speaker on and off. If the volume is changed or the
speaker toggled from another application then SoundCon updates the volume
slider and speaker button automatically. Note though that the volume is
independant of the normal system volume so other system-volume controllers
will have no effect.

The percentage above the volume slider shows the volume that will be used
when the slider is pushed right to the top. If you click on it, it will
switch between 100% and 200%; the latter mode allowing a sample to be
amplified. Distortion due to clipping will occur if the sample is amplified
too much.

The writable icon box beside the volume slider is the numeric setting of the
volume. You can type in a value here to set the volume if you wish.

4.3.3  Mono-echo mode

Mono samples can be played with a simulated stereo effect by having two
channels playing the same thing with one lagging slightly behind the other.
Click on the mono echo button (under the speaker button) to toggle this
feature on and off. The echo delay is set in the preferences. This option has
no effect on stereo samples and has not been implemented for ADPCM formats.

4.3.4  Section mode

Clicking the third button from the top toggles section mode. When off, a
sample will start from the beginning and play right through to the end as
expected. When on, the start and end can be set within the sample to play
only the selected section. Hopefully, in a later version this will also be
used to convert a section of the sample. Currently it only effects playback.

The start and end times can only be set when section mode is on. To change
them, either click on the start or end time and enter a valid time index or
drag the section markers underneath the progress bar. To accept a typed-in
time, move the caret off the field or click on play. The section markers will
move to reflect the entered time.

Note that the start and end times are subject to cueing restrictions imposed
by sample formats so that the time may be 'rounded' to a nearby time.
Currently ADPCM samples are only formats that can't be cueued to an arbitrary
position. The cue step size depends on the ADPCM block size.

4.3.5  Looping mode

Clicking the bottom button toggles looping mode. When off, the sample (or
section off) plays and stops as normal. When on, the sample will restart when
it reaches the end and play ad infinitum. Pressing the stop button to make it
stop.

Currently restarting is done by the application (as opposed to being done
automatically by the play module) with the effect that restart may not be
immediate if the wimp is busy.



4.4  Converting the sample to another format
============================================

Open the conversion window from the info window or icon bar menus. The
current destination format is shown with the usual elements of a save box.
Change the format, sample rate and filename (if current settings are not
suitable) and drag the icon to where you want the new sample to be or click
OK/press Return if a complete path is already present. The conversion
progress window will open and the conversion will occur in the background.
The conversion can be paused if you need the computer to be more responsive
for a while or aborted by clicking the appropriate button.

The filename initially present in the convert window will depend on the
preferences (see Preferences for options).

The conversion produces a sample (in the specified format) so that playing
it at the speed set in the 'Rate' box will sound the same as the original
sample played at the speed set the 'Frequency' box of the 'Interpret As'
section. That is, the sample is resampled at the new frequency. If the
frequencies are different then new samples are generated by linearly
interpolating between the original samples.

4.4.1  Options

Clicking Menu in the conversion window to see the conversion options. (In a
future version, there will be more options and they will probably displayed
in the window).

  - Auto chnls. When this is selected, loading a new sample causes the
    default output format to have the same number of channels as the source,
    if the output format permits. This can also be set in the preferences but
    toggling it here does not effect the preference setting.
    
  - Stereo>Mono. Converting from stereo to mono can be done in one of three
    ways (selected in the sub-menu):
    
    - Mix. The channels are mixed by averaging the instantaneous amplitudes.
    - Left. The left channel is extracted and the right channel is ignored.
    - Right. The right channel is extracted and the left channel is ignored.

See the file Docs.Formats for a description of the supported formats and
their sub formats.


4.5  Preferences
================

The preferences dialogue is opened from the icon-bar menu. It allows SoundCon
to be customised to some extent. Any changes you make have no effect until
one of the buttons at the bottom the main window are pressed:

  - Save. Make the change take effect and save them them to disc. Next time
    SoundCon is loaded the saved preferences will be loaded. Clicking with
    select, closes the window. Clicking with adjust keeps the window open.
    
  - OK. Make the changes take effect. Clicking with select, closes the
    window. Clicking with adjust keeps the window open.
    
  - Cancel (also window close icon). Throw away changes and close the window.


4.5.1  Default Conversion format

This controls what output format will initially be in the conversion save box
when the program is loaded. This format may also be set on loading a new
sample (see Auto Load Actions below). The effect of these settings is
described in 'Converting a sample' above.


4.5.2  Interpret Unknown As

When an unrecogised sample is loaded, the data will be initially interpreted
according the settings in this box. The pop-up menus are identical to those
for the Interpret As part of the info window (see 'Changing The
Interpretation' above).


4.5.3  Auto Actions On Load

Any combination (including none) of the following actions are performed when
a new sample is opened.

  - Open info window: The window displaying the information on the sample is
    opened.

  - Open convert window: The conversion/save window is opened.

  - Open play window: The play control window is opened.

  - Default format: The format and frequency used for the output sample is
    set from the Default Conversion Format part of the preferences.

  - Convert: The conversion process is started using the format and filename
    determined from other preference settings.

  - Play: The sample is played.

If either convert or play (or both) are selected and there is at least one
sample in the queue then the sample is cleared after the respective operation
has completed to allow the next queued sample to be processed automatically.
If convert AND play are selected then the sample is cleared after both have
finished.


4.5.4  File naming

These options control what filename will appear in the conversion/save box
when a new sample is opened:

  - Do not update name: The writable icon is left the same as when it was
    last used.

  - New leaf with previous path: Everything up to the last '.' is preserved
    and remainder (the leaf) is replaced with the leaf name of the source
    sample. This is the only useful file naming option for queue processing.

  - New leaf-only name: The filename is set to the leaf name of the source
    sample.

  - Add/change extentions: When this option is set an extension of the form
    '/XXX' is appended to the filename (after one is generated from the
    above options). XXX is an MS-DOS like abbreviation like WAV, AIF, RAW
    etc. The leaf is not truncated to 10 characters in case you want to copy
    it to a filing system supporting longer filenames.

If the auto-convert option and 'New leaf with previous path' is not selected
then a warning is displayed when you exit the preferences window because
queue processing can only be done with that option set. (no update can be
used but all the samples will overwrite each other!)

    
4.5.5  Sound

This section specifies how to set up the sound system on loading SoundCon:

  - Set volume: If this option is set then the playback volume is set
    according the slider below otherwise it is left unchanged. Note that
    this only affects the volume for the PlaySample module which is
    independant of the normal system volume.

  - Don't set speaker: The speaker is left in the current state (on or off).

  - Speaker off: The speaker is switched off.

  - Speaker on: The speaker is switched on.
  
  - Mono echo: Set the delay between channels in centiseconds (0-99) for a
    simulated stereo effect on mono samples. If this mode is not selected
    then mono samples are played using one channel only. This option has no
    effect on stereo playback or ADPCM formats. The actual delay is limited
    to 2048 sample frames so the maximum delay in seconds is 2048/rate. eg at
    11111Hz 2048/11111 = 18cs. This option is enabled and disabled in the
    playback window.
    
  - Frequency modulation: Select whether to control the frequency accurately
    using frequency modulation. When on, sound is played at the current
    sound system frequency and the sample stream is modulated to keep the
    required pace. When off, the sound system frequency is set as close as
    possible to the frequency required by the sample and the sample stream is
    sent verbatum.
    
    The advantage of frequency modulation is precise frequency control
    including correction for VIDC speeds that normally cause speed problems.
    There may be some slight noise associated with the modulation which is
    why the unmodulated option is present; the sample will be as clean as
    possible but probably too fast or slow depending on how close the sample
    frequency is to the nearest sound system frequency.


4.5.6  General

Miscellaneous options

  - Dble click load: SoundCon repsonds to the Dataload message allowing it to
    load samples by double clicking on them. It attempts to load any file
    that is 'launched'. If it recognises it, loads it otherwise it is ignored
    so other applications still get a look in.
    
  - ArcWeb render: When this option is set, SoundCon responds to rendering
    requests from ArcWeb. If the file to be rendered is a recognised sound
    format and SoundCon is idle then it will be loaded and played.
    
  - Auto Set Type: This allows files recognised by contents to be given the
    correct filetype when they are loaded (if the filing system permits). No
    action is taken if the format is unrecognised.

  - Auto #chnls: When selected, the number of channels in the output format
    will be set to the number of channels in the source (if the format
    permits). This happens when the sample is first loaded and can still be
    changed manually.
    
  - Dequeue on use: When files are taken from the queue and 'loaded' as the
    current sample, this option determines whether the entry will be removed
    from the queue (option on) or not.

  - Font: This sets the font that SoundCon will use for all its text. RiscOS
    3.5 (and above) users should leave this set to 'system font' so that the
    OS will use the current desktop font. Apparantly there is a bug in RO3.5
    that causes font problems if an outline font is used in the slab buttons.
    This feature is mainly for use in OS versions before 3.5. Note that if
    you have *lots* of fonts the menu won't display all of them.
    
  - Sprites: The set of sprites used (they're only used in the playback
    window currently) can be selected from the pop-up menu. If a square-pixel
    (hi-res, 22 suffix) sprite file exists and you are using a square-pixel
    mode then that is loaded. If you are not using a sqaure-pixel mode or the
    '22 file does not exist then the lo-res (mode 12) sprites are loaded
    instead.


4.6  Queue processing
=====================

SoundCon can process a queue of samples as well as single samples; this is
so that a whole bunch of samples can be converted (or played) without user
intervention. The restrictions are that all the samples in the batch will be
converted to the same format and will all be placed in the same directory.


4.6.1  Loading the queue

One or more samples may be explicitly loaded into the queue by dragging
it/them into the queue window (opened from the icon bar menu). If more than
one sample is dragged to into SoundCon (to any window, or the icon-bar) then
the first will be dealt with normally (ie as if it was a single file) and the
rest will be queued automatically.


4.6.2  Loading a queued sample

The queue works on the principle that when there is no sample open, the one
at queue pointer is opened (and removed from the queue if dequeueing is
selected). The current sample will be cleared and a new new loaded from
the queue when:

  - You clear it manually from the menu in the Sample Info window.
  - The 'next track' button is pressed in the play window.
  - You double-click on a queue entry.
  - A sample has finished converting and the 'Auto Actions on Load/Convert'
    option is set from the preferences.
  - A sample has finished playing and the 'Auto Actions on Load/Play' option
    is set from the preferences.
    
All but the first instance do nothing if the queue pointer is not pointing to
anything (eg, queue empty or end-of-queue) so that the last sample in the
queue remains the current sample.

The queue pointer can be set manually by clicking on a queue entry.


4.6.3  Batch conversion

If SoundCon is set to auto-convert on load, all the files in the queue
will convert automatically. Note however that when the first file is opened
the warning message 'To save, drag the file to a directory display' is
displayed. The first file needs to be dragged manually to determine where to
save the samples. You should also select what you want them all converted
to at this point. A result of this is that conversion can only progress
automatically if the file naming method is set to 'New leaf with previous
path' otherwise the warning will be given for every file or the files will
all have the same name and overwrite each other. If you select auto-convert
and the file naming is set to something inappopriate, you are warned when
you close the preferences window.

You will need to change the format and output path (if necessary) before you
load the queue a second time because there will now be suitable defaults to
begin conversion immediately. Alternatively, clear the filename or the entire
sample to set things up after the queue is loaded.


4.6.4  The queue menu

When the menu button is pressed in the queue window the selected entry is
highlighted and the menu entries above the dividing line operate on that
entry.

  - Delete: The selected entry is removed from the queue.
  
  - Delete to start: All entries *before* the selected entry are removed
    making the selected entry the first one in the queue.
  
  - Delete to end: All entries from the selected entry onward are removed.
  
  - Clear queue: All entries are removed from the queue.
  
  - Shuffle: The queue entries are arranged randomly (for if you want to use
    SoundCon like a CD player).
  
  - Remove on use: A toggling option to select whether entries should be
    removed from the queue when they are used or not. This is the same as the
    preference option 'dequeue on use'.
  
  - Save queue: A particular group of samples (the queue) can be saved to be
    loaded back into SoundCon later. Currently the only way to re-load a
    saved queue is to double-click on it while SoundCon is loaded.


4.7  Using SoundCon with ArcWeb
===============================

From version 1.40 SoundCon can play samples for ArcWeb by responding to its
rendering requests. The 'ArcWeb render' preference must be set and SoundCon
must be idle (ie not converting or playing another sample) to repsond to
ArcWeb requests because it 'loads' the sound as its current sound which would
mean halting any previous activity. While the sound is 'loaded' it can be
converted/saved or played again until a new sound is loaded or it disappears
from the ArcWeb cache.


5. History/Future
=================

See the file !SoundCon.Docs.HistFuture


6. Problems?
============

I have tried to ensure that SoundCon can process a wide variety of sample
formats and sub-formats and because of this it has been hard to find original
files to test them all with. Please let me know (e-mail address below) if you
encounter a sample that SoundCon doesn't process correctly; several small
bugs have been fixed because of this kind of feedback. I'd also be interested
to hear if there are any other unsupported formats that could be included in
SoundCon's repertoire; bearing in mind that I need some information about the
format before I can implement it.

The file !SoundCon.Docs.HistFuture lists known bugs/features and additions
being considered for future versions.


7. Acknowledgements
===================

Thanks to the following people who mades useful suggestions, supplied
information or did testing:

Andrew (what is your other name anyway?!), Stewart Brodie, Trevor Johnson,
Jasper Wallace, John Brand, Are Leistad, Nick Bannon, Chris Poole and Matthew
Norrie for the much needed sprites!

